playbyplay
A query to this endpoint without a qualifying query parameter will return an error. Results must be filtered by one or more of the following: id, season, player, game, team, date or date range (start-end; last). Passing an id parameter will return a single PBP entry (with no additional metadata).
Please note that this endpoint can be used synonymously as pbp.
MLB PBP for 7/1/2016
https://api.natstat.com/v1/playbyplay/MLB/?key=XXXX-XXXXXX&format=xml&date=20160701
Download sample
Parameters
Path
| Name | Required | Type | Description |
|---|---|---|---|
level |
required | string | The competition level to retrieve information for. A full glossary can be found in the Path Parameters section |
Query
| Name | Required | Type | Description |
|---|---|---|---|
key |
required | string | A valid API key in XXXX-XXXXXX format |
format |
optional | string | The preferred data format: xml, json or php (presented as a SimpleXML object). The default is json |
max |
optional | number | The number of results per page to return. The default value is 100, and the maximum allowed parameter value is 1000. This value is echoed back as Max_Results in the meta block |
page |
optional | number | The pagination page number. This value is echoed back as Page in the meta block. The meta block also contains the Total_Results of the query. If there are further results, a fully-formed Next_Page URI containing a pre-filled &page=X value will be returned |
id |
optional | number | A valid play-by-play ID code, which returns details for that entry (A list of available play-by-play entries can be retrieved from this endpoint by not passing an ID code.) |
team |
optional | number | A valid team ID code. A list of teams can be retrieved from the teams endpoint |
season |
optional | number | A valid season ID code, formatted as the year that a season completes, in YYYY format. A list of available seasons can be retrieved from the seasons endpoint |
search |
optional | string | For general search of endpoint contents. Queries of four characters or less will be ignored |
player |
optional | number | A valid player ID code. A list of teams can be retrieved from the players endpoint |
game |
optional | number | A valid game ID code. A list of games can be retrieved from the games endpoint |
date |
optional | string | The date to limit matched results to. The API will attempt to translate the date, but YYYYMMDD or YYYY-MM-DD are preferred |
start |
optional | string | The start date from which to include matched results (inclusive). The API will attempt to translate the date, but YYYYMMDD or YYYY-MM-DD are preferred |
end |
optional | number | The end date to which to include matched results (inclusive). The API will attempt to translate the date, but YYYYMMDD or YYYY-MM-DD are preferred |
last |
optional | number | Number of days previous to today's date, to specify a date range from which to match results |
Response
| Name | Required | Type | Description |
|---|---|---|---|
ID |
number | The unique identifier for the record | |
Explanation |
string | A plain text description of the event | |
primary |
object | Contains players metadata about the most relevant player in the event | |
Name |
string | The full name of the player | |
pitcher |
object | Contains players metadata about the pitcher | |
ScoringPlay |
boolean | Whether the play resulted in a score, in Y/N format | |
Tags |
string | The tags associated with this event, pipe separated | |
TheCount |
string | The count at the time of the event, in B-S format (baseball only) | |
PitcherHanded |
string | Returns R, L or S | |
BatterHanded |
string | The handedness of the batter, L R or S | |
TheDiff |
string | The difference between the two teams' scores. Term invented by the now-Rocket Mortgage Fieldhouse in Cleveland | |
team |
object | Includes teams metadata about the relevant team | |
Team |
string | The teams name of the relevant team | |
opponent |
object | Contains teams metadata about the opposing team | |
Opponent |
string | The teams name of the opposing team | |
game |
object | Includes games metadata about the game the event took place in | |
Game_ID |
number | The games ID of this game | |
GameDay |
date | The date of this game, in YYYY-MM-DD format | |
Description |
string | A plain text description of the event | |
Visitor |
string | The teams name of the visiting team | |
Visitor_ID |
number | The teams ID of the visting team | |
ScoreVis |
number | The visiting team's score in the relevant game | |
Home |
string | The home team of the game the event took place in | |
Home_ID |
number | The teams ID of the home team | |
ScoreHome |
number | The home team's score in the relevant game | |
Half |
number | The period, half or inning in which the event occurred | |
Inning |
string | The inning the event took place in (baseball only) | |
Sequence |
string | The sequence of pitches or subevents in the event | |
venue |
object | Contains venues metadata about the location of the game | |
CityState |
string | The city and state where the game was played | |
Longitude |
number | The longitude of the venue where the relevant game was played | |
Latitude |
number | The latitude of the venue where the relevant game was played |